PATH Mac OS X Server Documentation > Mac OS X Server Release Notes

Mac OS X Server Developer Release Notes:
Developer Documentation

These notes concern developer documentation for the Yellow Box and for the Rhapsody core operating system, and describe how you can access this documentation. For Yellow Box on Windows, substitute the value of NEXT_ROOT for /System on all installed file locations given below. These release notes do not cover developer documentation for the Enterprise Objects Framework or WebObjects products.

Developer documentation is mostly in HTML and PDF format on both Rhapsody and Yellow Box for Windows platforms.

Notes Specific to Developer Release

Documentation Access

You have the following ways to access developer documentation on Rhapsody and Yellow Box for Windows; some items are marked as new in Developer Release 2:

Developer's Home Page

New-This feature, new and still incomplete in this release, is designed to provide a central access point to the developer documentation on your machine. The Developer's Home Page is created by a script that runs after documentation packages are installed. Based on the documentation and other resources it finds, the script assembles the Developer's Home Page and a series of indexes for the individual products and for the combined documentation set.

In this early version, only a handful of documentation sets are participating with the script. Later, however, the plan is to integrate all Apple-supplied documentation sets and those of third-party developers. Whenever documentation sets are added or removed from your system, the script will recreate the Developer's Home Page, indexes, and other script-generated pages.

On a Rhapsody machine, you can find the Developer's Home Page at /System/Documentation/Developer/DevelopersHomePage/DevelopersHomePage.html. This home page lists, for Developer Release 2, the core Apple-supplied developer documentation and provides indexes to much of the API reference.

"Static" Home Page

For Developer Release 2, when you choose "ProjectBuilder Help" from Project Builder's Help menu, a set of HTML pages is displayed that allows you to navigate through most of the installed developer documentation. This hand-created set of "home pages" gives access to developer documentation for the Yellow Box and Rhapsody operating-system. It does not include any indexes. It will eventually be replaced by the Developer's Home Page.

Class Browser

New - Project Builder now includes a class browser, accessible from the control panel on the main project window.

The class browser gives you a flat or hierarchical view of the Yellow Box frameworks and where your custom classes fit into them. It allows you see the declared and inherited instance variables and the implemented and inherited methods for each class.

The class browser also lets you access the documentation for a class, protocol, method, function, type, or constant. Just click the book icon next to an item to display the documentation in a Project Builder window.

DocFinder Application

New - The DocFinder application uses the V-Twin search engine to perform a fast indexed search of developer documentation. The index is pre-built and references all of the documentation that is displayable in HTML format. (For this reason, man pages are not included in the index. ) Covered documentation includes conceptual and task-based material as well as API reference.

To use DocFinder, just enter a whole or partial word in the "Search for:" field. The results--which are documents containing the entered string--are displayed in a table view. Results are listed in weighted order. Double-click a line to open a document in an application that reads HTML--a browser if one is installed, otherwise TextEdit.

DocFinder does not scoll to and highlight matching strings within a document; you can find the string in the document using whatever search mechanisms the displaying application offers. DocFinder.app is located in /System/Developer/Demos. This application is a temporary searching solution for developer documentation; a fuller-featured, more integrated solution will appear in a future release.

Project Find

The Project Find panel of Project Builder performs searches for symbols in indexed projects. The symbols can be any class, protocol, method, function, macro, type, or constant of any imported framework or library, or of the project itself, including all subprojects. If there is API documentation for a symbol summarized on a search-result line, a book icon appears at the start of the line. Click the icon to display the reference documentation in Project Builder.

There is a way to inquire directly about symbols in your code. Click the Help button (the ? icon) in Project Builder's main window, hover the question-mark cursor over the code until a symbol or message in highlighted, then click the mouse button. The Project Find panel is displayed with the selected symbol entered in the Find field.

Note: If your project is not indexed, most of the features described above are not available.

Web Browser and PDF Reader

You can view HTML on Rhapsody using the web browser OmniWeb and PDF documentation using the PDF reader OmniPDF. These applications, and their supporting frameworks, are among the third-part applications on the Rhapsody CD-ROM. On Windows you can read the documentation using whatever browser and PDF reader you have installed.

Developer documentation is installed in /System/Documentation/Developer except for API reference documentation, which is installed in the associated framework at /System/Library/Frameworks/framework.framework/Resources/English.lproj/Documentation (where framework is "AppKit" or "Foundation").

The CD-ROM on which Rhapsody comes also has an HFS partition which contains the developer documentation set. So if you don't have a web browser on Rhapsody, you can view the HTML documentation using your favorite Macintosh web browser. If you have no web browser available at all, you can view the HTML files using the TextEdit application (links, however, are disabled).

New Documentation

The following new documentation has been written for the Developer Release. You can access most of this documentation from the Developer's Home Page.

Scripting Documentation

This release contains reference documentation for the major scripting classes in the Yellow Box. In addition, it includes conceptual and task documentation related to scripting as programming topics. The topics are:

"Application Design for Scripting, Documents, and Undo"
"Making Your Applications Scriptable"
"Creating Suite Definitions and Suite Terminologies"

The following scripting classes are documented:

NSScriptClassDescription
NSScriptCommandDescription
NSScriptCommand
NSScriptSuiteRegistry
NSScriptExecutionContext
NSObjectSpecifier

The NSObjectSpecifier reference documentation includes summaries of concrete subclasses, each of which is related to an AppleScript reference form. These summaries include descriptions of added and overridden methods. The object-specifier subclasses are:

NSPropertySpecifier
NSIndexSpecifier
NSRangeSpecifier
NSRandomSpecifier
NSMiddleSpecifier
NSRelativeSpecifier
NSWhoseSpecifier

The NSObjectSpecifier reference documentation also describes the NSPositionalSpecifier class (instances of which represent insertion points) and the NSSpecifierTest and NSLogicalTest classes, instances of which are used by NSWhoseSpecifier objects.

The reference documentation erroneously states that the scripting classes belong to the Foundation framework; they belong instead to the Scripting framework. In addition, the AppKitScripting framework includes other scripting-related methods, most of which are in categories on existing Application Kit classes. These methods are currently undocumented.

Class Specifications

Many new classes have been added to the Yellow Box frameworks for Developer Release 2 and API reference documentation exists for most of these new classes:

Objective-C:

NSUndoManager
NSDistributedNotificationCenter
NSDocument
NSDocumentController
NSWindowController

In addition, most of the Objective-C specification files available in earlier releases have been updated. The NSURL class was added to the Yellow Box too late to be documented for this release.

Java:

NSAlertPanel
NSModalSession
NSRect
NSRange
NSSize
NSPoint
NSMutableRect
NSMutableRange
NSMutableSize
NSMutablePoint

These Java classes are native Java implementations of behavior implemented as functions or structures in Objective-C.

Java Documentation

In addition to the Java class specifications listed above, the Developer Release includes other material related to Java development on Rhapsody and Yellow Box for Windows systems:

"Developing Java Applications: A Tutorial": Steps you through the creation of a simple application that is written in the Java language but that uses Yellow Box and Java objects. Discusses how to use the developer tools, Interface Builder and Project Builder, to create a typical application, and how to create custom controller classes (which inherit from java.lang.Object) and custom view classes (which inherit from an Application Kit class). It also describes how to use the development environment to create 100% Pure Java applications.
You should not run this tutorial from within Project Builder. The tutorial is dependent on HTML framesets, and Project Builder does not support frames. Instead, display the tutorial in a web browser such as OmniWeb (on Rhapsody) or Netscape Navigator (on Macintosh and Windows). See Web Browser and PDF Reader above for your options. To begin the tutorial, open index.html in:

/System/Documentation/Developer/YellowBox/TasksAndConcepts/JavaTutorial/JavaTutorialIntro

(On Windows substitute the value of NEXT_ROOT for /System.) A PDF version of this tutorial is also available in the PDF subdirectory of the JavaTutorial directory.
"Skeletal" Yellow Box Java API reference: The Developer Release includes Java class and interface specification files. Except for the Java classes listed above, these specifications have no descriptive content. However, they do present method prototypes and, in most cases, provide HTML links to the description of the corresponding Objective-C method.

You cannot access this Java referemce documentation through the Project Find panel of Project Builder. You must use one of the other methods, such as the static home page, Developer's Home Page, the DocFinder application, or a web browser. These documentation files are installed in the following locations:

/System/Library/Frameworks/Foundation.framework/Resources/English.lproj/Documentation/Java/Reference
/System/Library/Frameworks/AppKit.framework/Resources/English.lproj/Documentation/Java/Reference

You can also use the JavaBrowser application to examine Java method prototypes. This application is located in /System/Developer/Applications. Once you launch this application, navigate to the Application Kit and Foundation packages:

com.apple.yellow.application
com.apple.yellow.foundation

Interface Builder and Project Builder Help

This release includes draft task-based documentation of the two major tools in the development environment, Project Builder and Interface Builder. The Project Builder HTML files describe how to create and manage projects, find information in project files, and localize projects. Future versions of this manual will include more information, such as how to build and debug projects.The Interface Builder on-line manual describes how to create connections and subclasses. Future versions will include more information, such as how to create and manage nib files and set options for the interface elements.

Special Release Notes

Some release notes address special topics, among them:

Other

File System Layout and Conventions describes the names, locations, and typical contents of the standard directories for system, local, and network files. It also discusses the search paths used for locating files. The documentation set now includes a glossary of terms specific to Rhapsody and the Yellow Box APIs.

Known Problems

The DocFinder application crashes on launch if indexed directories are moved after the indices are built. All indexed documentation is installed as part of the Developer Documentation package. To avoid this bug, do not remove subsets of /System/Documentation/Developer after the Developer Documentation package is installed. (On Yellow Box for Windows platforms, substitute the installation directory for /System.)
Yellow Box for Windows only : The DocFinder application installed from the "Deployment" distribution of Yellow Box for Windows does not work and crashes if launched. The DocFinder application installed from the "Development" distribution does work, however.
The human interface for Rhapsody and its applications is undergoing rapid change. For this reason, you may encounter instances where the documentation does not accurately reflect what you see. These discrepancies will be corrected in future releases.
Project Builder does not correctly handle links from the Java method descriptions to their Objective-C counterparts. Project Bulder displays the Objective-C file, but does not scroll down to the method. A workaround is to view the Java reference documentation in a web browser.
Project Builder relies upon a private framework to parse HTML code. Because this framework is optimized for WebObjects, it is less tolerant of non-standard HTML code than are web browsers. If in Project Builder you encounter entire pages or parts of pages that are not displayed or links that seem broken, it is probably because of HTML code that was not parsed. We will fix this HTML in future releases. The workaround is to view the affected file in a web browser.
Reference documentation on NSDataLink, NSDataLinkPanel, and NSDataLinkManager was mistakenly included in this release. These classes are obsolete. You should ignore these class specifications, and do not include any APIs from them in your code.
The malloc(3) man page included with the DR2 version of Rhapsody is the man page for BSD 4.4, and does not match the behavior of malloc under Rhapsody. You can download the correct malloc man page from the Rhapsody Developer Documentation web site at http://developer.apple.com/techpubs/rhapsody/rhapsody.html. Install it in /usr/share/man3/.

Tutorial Applications

The applications for "Discovering Rhapsody: A Developer Tutorial" and the tutorial itself have discrepancies and other problems that you should be aware of. In particular, the ToDo application project contains some bugs that were not discovered in time to fix for this release. You can download a fixed version of this example project and the other tutorial projects (TravelAdvisor and CurrencyConverter) from
http://developer.apple.com/techpubs/rhapsody/rhapsody.html.

The ToDo tutorial application project is not included on Yellow Box for Windows. You can download this project from the web site indicated by the URL above.

Page 148 of the PDF book "Discovering Rhapsody: A Developer Tutorial" shows a code example that contains an error. If, in following the tutorial, you copy the code from the book and compile it, ToDo will crash if you launch the application by double-clicking its icon in the workspace. The method initWithFile: begins in this way in t:he book:

- initWithFile:(NSString *)aFile
{
    NSEnumerator *dayenum;
    NSDate *itemDate;
     [super init];
     if (aFile) {
        activeDays = [NSUnarchiver unarchiveObjectWithFile:aFile];
        if (activeDays) 
            activeDays = [activeDays retain];
        else {
            NSRunAlertPanel(@"To Do", @"Couldn't unarchive file %@", nil, nil, nil, aFile);
            return nil;
        }
    } else {
        activeDays = [[NSMutableDictionary alloc] init];
        [self setCurrentItems:nil];
    }
     if (![NSBundle loadNibNamed:@"ToDoDoc.nib" owner:self] )
          return nil;
/* etc. ... */

Corrected, the code example should read as follows:

- initWithFile:(NSString *)aFile
{
    NSEnumerator *dayenum;
    NSDate *itemDate;
     [super init];
     if (![NSBundle loadNibNamed:@"ToDoDoc.nib" owner:self] )
          return nil;
     if (aFile) {
        activeDays = [NSUnarchiver unarchiveObjectWithFile:aFile];
        if (activeDays) {
            activeDays = [activeDays retain];
            [self setCurrentItems:[activeDays objectForKey:
                [calendar selectedDay]]];
        }
        else {
            NSRunAlertPanel(@"To Do", @"Couldn't unarchive file %@", 
                nil, nil, nil, aFile);
            return nil;
        }
    } else {
        activeDays = [[NSMutableDictionary alloc] init];
        [self setCurrentItems:nil];
    }
/* etc. ... */

In other words, the statement that loads the nib file should should come right after the invocation of super. Notice also the inclusion of the following statement under the "if (activeDays)" block:

[self setCurrentItems:[activeDays objectForKey:[calendar selectedDay]]];

You should move this statement from the awakeFromNib method in ToDoDoc.m.

The ToDo inspector panel has its "Release when closed" attribute checked, causing the application to crash if the inspector is opened multiple times. Uncheck this box and recompile the application to fix this problem.
The "Discovering Rhapsody" tutorial applications that are installed in /System/Developer/Examples/AppKit--CurrencyConverter, TravelAdvisor, and ToDo--have had their menu layouts changed to conform to current guidelines. The "Discovering Rhapsody" PDF book, however, has not yet been changed to reflect this new layout.

Mac OS X Server Developer Release Notes: Developer Documentation